JST Tool

A JSON Schema Transformation (JST) in simple terms is the transformation of data usually from a web-based application to a company’s internal database or vice versa. Transferred JSON data has to be reformatted in order to work with other applications not written in JSON or if the data is in a different non-JSON format.

The Itential Automation Platform (IAP) has a built-in JSON Schema Transformation Tool which allows you to leverage pre-built templates that are editable or you can create a new transformation. This guide will illustrate how to use both the pre-builts and how to build your own transformation utilizing the JST Tool.

Create a New JST

To access the transformation tool and create a new JST:

1. Go to IAP → Automation Studio → Transformations.

   Figure 1: Transformations

   

2. From the Transformations collection menu, you can search for an existing JST or select one from the dropdown list.

3. To create a new JST, click the plus sign (+) in the circle located in the top toolbar above the menus.

   Figure 2: Create New

   

4. The Create dialog will open. Select Transformation from the dropdown menu.

   Figure 3: Select Transformation

   

5. Enter a name for your JST (this is a mandatory field) and a description (which is an optional field), and then click Create to save the new JST.

   Figure 4: Create New JST

   

6. A blank canvas will open. This is where the new JST will be created. Click the plus sign (+) to add an incoming schema.

   Figure 5: Blank JST Canvas

   

7. There are three (3) different ways to create a new JST:

   • Cut and paste a schema into the left side window (editor).
   • Paste the information in the right side window and click the Infer Schema From Example JSON link.
   • Click the ↑ Schema upload button and navigate to the location of the JSON file you are going to use.

   
   

   Figure 6: JSON Import Methods

   

8. For this example, the Infer Schema method was used to import the JSON.

   • Paste the example JSON into the right side window and click the Infer Schema From Example JSON link.
   • If the code is correct the Save button will become enabled and appear blue.
   • Click Save and the JSON will appear on the Transformation canvas.

   
   

   Figure 7: Infer Schema

   

9. The inferred JSON created in the previous step is displayed under the Incoming Schemas column.

   Figure 8: Incoming Schemas Column

   

10. Now the rest of JST can be built using the methods and functions in the column on the right side.

    Figure 9: Methods & Functions

    

11. You can test your Transformation by clicking the Run button on the left side of the canvas. Lastly, make sure to save all changes, this will allow you to use the Transformation again.

    Figure 10: Run & Save

    

Using Pre-Built JST

To use a pre-built JST:

1. Select the type of pre-built you want to use from the pre-built dropdown on the right side.

   Type	Description
   Template Example	Allows you to concatenate (i.e., bring one or more) strings together while using embedded expressions and improving readability.
   Map Example	Creates a new array with the results of a function that are used on every member in the calling array.
   Find Example	Will return the value of the first element in the array that satisfies the provided testing function. If there is no element that meets the testing function, undefined is returned.
   Query Example	Allows you to set the parameters of what you are searching for. The query should return any and all elements that meet the search criteria.

   
   

   Figure 11: Pre-built JSTs

   

2. Once you have selected a pre-built JST to use, click the Edit button above the incoming schema.

   Figure 12: Edit Pre-built

   

3. Select the method for adding your data (i.e., cut/paste, infer, or upload) as referenced in the previous section.

4. Paste the JSON in the right side (white canvas) window and click the Infer Schema From Example JSON link.

   Figure 13: Infer Schema

   

5. Click Save to continue.

   Figure 14: Save JSON

   

6. Once the JSON data is in the pre-built JST template, create (draw) connections between the incoming and outgoing schemas. When you select a field from the Incoming Schema column, the corresponding Outgoing Schemas fields will show blue if it is a match or red if it is not a match.

   Important: The field types need to match (i.e., object to object, integer to integer, etc.).

   Figure 15: Match Fields

   

7. Click the Run button to test.

   Figure 16: Run to Test

   

8. The Output tab at the bottom of the canvas will display the results.

   Figure 17: Review Output